/* 
 *  Copyright 2012 CodeMagi, Inc.
 * 
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package com.codemagi.login;

import com.codemagi.login.model.IUser;
import com.codemagi.login.model.IUserPreferences;
import com.codemagi.servlets.AppException;
import javax.servlet.http.*;
import org.exolab.castor.jdo.Database;
import org.exolab.castor.jdo.PersistenceException;

/**
 * Client class for Login application. This class is implemented as a 
 * servlet so that it can access pooled database connections configured
 * by the application server.
 */
public interface ILoginClient {

    /** 
     * Returns the authorized user that made the request, without checking for login
     */
    public IUser getUser(HttpServletRequest request) throws LoginException;


    /** 
     * Returns the user that made the request, optionally checking for login 
     */
    public IUser getUser(HttpServletRequest request, boolean checkLogin) throws LoginException;


    /** 
     * Returns the user preferences for the user that made the request.
     * NOTE: Preferences can only be returned for logged in users. 
     */
    public IUserPreferences getUserPreferences(HttpServletRequest request) throws LoginException;


    /** 
     * Returns the User that matches the passed email address
     */
    public IUser getUserByEmail(String emailAddress) throws AppException;


    /**                                                                                                       
     * Returns a User object when passed an email address. This method throws                         
     * an AppException if the email address is not found in the database.                                 
     */
    public IUser getUserByEmail(String email, Database db) throws AppException, PersistenceException;


    /**                                                                                                                   
     * Returns a User object when passed an email address.                                                                 
     *                                                                                                                      
     * @param email   The email address to search for                                                                    
     * @param db      Database instance to use                                                                             
     * @param create  If true, this method will attempt to create the new user                                             
     */
    public IUser getUserByEmail(String email, Database db, boolean create) throws AppException, PersistenceException;


    /**                                                                                                               
     * Returns the number of logged in users who have accessed the site within some time period (typically the last 30 minutes)
     */
    public int getUsersOnline();

}
